Business Listings Search API provides results containing information about business entities listed on Google Maps in the specified categories. You will receive the address, contacts, rating, working hours, and other relevant data. The provided results are specific to the selected location (see the List of Locations) settings.
Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-dashboard
# Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-dashboard
login="login"
password="password"
cred="$(printf ${login}:${password} | base64)"
curl --location --request POST "https://api.dataforseo.com/v3/business_data/business_listings/search/live"
--header "Authorization: Basic ${cred}"
--header "Content-Type: application/json"
--data-raw "[
{
"categories": [
"pizza_restaurant"
],
"description": "pizza",
"title": "pizza",
"is_claimed": true,
"location_coordinate": "53.476225,-2.243572,10",
"order_by": [
"rating.value,desc"
],
"filters": [
[
"rating.value",
">",
3
]
],
"limit": 3
}
]"
<?php
// You can download this file from here https://cdn.dataforseo.com/v3/examples/php/php_RestClient.zip?202197
require('RestClient.php');
$api_url = 'https://api.dataforseo.com/';
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-dashboard
$client = new RestClient($api_url, null, 'login', 'password');
$post_array = array();
// simple way to get a result
$post_array[] = array(
"categories" => ["pizza_restaurant"],
"description" => "pizza",
"title" => "pizza",
"is_claimed" => true,
"location_coordinate" => "53.476225,-2.243572,10",
"order_by" => ["rating.value,desc"],
"filters" => [
[ "rating.value",">",3 ]
],
"limit" => 3
);
try {
// POST /v3/business_data/business_listings/search/live
// the full list of possible parameters is available in documentation
$result = $client->post('/v3/business_data/business_listings/search/live', $post_array);
print_r($result);
// do something with post result
} catch (RestClientException $e) {
echo "n";
print "HTTP code: {$e->getHttpCode()}n";
print "Error code: {$e->getCode()}n";
print "Message: {$e->getMessage()}n";
print $e->getTraceAsString();
echo "n";
}
$client = null;
?>
from client import RestClient
# You can download this file from here https://cdn.dataforseo.com/v3/examples/python/python_Client.zip
client = RestClient("login", "password")
post_data = dict()
# simple way to set a task
post_data[len(post_data)] = dict(
categories=[
"pizza_restaurant"
],
description="pizza",
title="pizza",
is_claimed=True,
location_coordinate="53.476225,-2.243572,10",
order_by=["rating.value,desc"],
filters=[
["rating.value",">",3]
],
limit=3
)
# POST /v3/business_data/business_listings/search/live
response = client.post("/v3/business_data/business_listings/search/live", post_data)
# you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if response["status_code"] == 20000:
print(response)
# do something with result
else:
print("error. Code: %d Message: %s" % (response["status_code"], response["status_message"]))
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
namespace DataForSeoDemos
{
public static partial class Demos
{
public static async Task business_data_business_listings_search_live()
{
var httpClient = new HttpClient
{
BaseAddress = new Uri("https://api.dataforseo.com/"),
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-dashboard
//DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
};
var postData = new List<object>();
// You can set only one task at a time
postData.Add(new
{
categories = new[]
{
"pizza_restaurant"
},
description = "pizza",
title = "pizza",
is_claimed = true,
location_coordinate = "53.476225,-2.243572,10",
order_by = new[]
{
"rating.value,desc"
},
filters = new object[]
{
new object[] { "rating.value", ">", 3 }
},
limit = 3
});
// POST /v3/business_data/business_listings/search/live
// the full list of possible parameters is available in documentation
var taskPostResponse = await httpClient.PostAsync("/v3/business_data/business_listings/search/live", new StringContent(JsonConvert.SerializeObject(postData)));
var result = JsonConvert.DeserializeObject<dynamic>(await taskPostResponse.Content.ReadAsStringAsync());
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (result.status_code == 20000)
{
// do something with result
Console.WriteLine(result);
}
else
Console.WriteLine($"error. Code: {result.status_code} Message: {result.status_message}");
}
}
}
The above command returns JSON structured like this:
All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method. When setting a task, you should send all task parameters in the task array of the generic POST array. You can send up to 2000 API calls per minute.
Below you will find a detailed description of the fields you can use for setting a task.
Description of the fields for setting a task:
Field name
Type
Description
categories
array
business categories
optional field
the categories you specify are used to search for business listings;
if you don’t use this field, we will return business listings found in the specified location;
you can specify up to 10 categories
description
string
description of the element in SERP
optional field
the description of the business entity for which the results are collected;
can contain up to 200 characters
title
string
title of the element in SERP
optional field
the name of the business entity for which the results are collected;
can contain up to 200 characters
is_claimed
boolean
indicates whether the business is verified by its owner on Google Maps
optional field
location_coordinate
string
GPS coordinates of a location
optional field location_coordinate parameter should be specified in the “latitude,longitude,radius” format
the maximum number of decimal digits for “latitude” and “longitude”: 7
the value of “radius” is specified in kilometres (km)
the minimum value for “radius”: 1
the maximum value for “radius”: 100000
example: 53.476225,-2.243572,200
filters
array
array of results filtering parameters
optional field you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported: regex, not_regex, <, <=, >, >=, =, <>, in, not_in, like, not_like
you can use the % operator with like and not_like to match any string of zero or more characters
example: ["rating.value",">",3]
you can receive the list of available filters by making a separate request to https://api.dataforseo.com/v3/business_data/business_listings/available_filters
order_by
array
results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order
you should use a comma to set up a sorting parameter
example: ["rating.value,desc"]note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example: ["rating.value,desc","rating.votes_count,desc"]
limit
integer
the maximum number of returned businesses
optional field
default value: 100
maximum value: 1000
offset
integer
offset in the results array of returned businesses
optional field
default value: 0
if you specify the 10 value, the first ten entities in the results array will be omitted and the data will be provided for the successive entities
offset_token
string
token for subsequent requests
optional field
provided in the identical filed of the response to each request;
use this parameter to avoid timeouts while trying to obtain over 100,000 results in a single request;
by specifying the unique offset_token value from the response array, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task Note: if the offset_token is specified in the request, all other parameters should be identical to the previous request
tag
string
user-defined task identifier
optional field the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response
As a response of the API server, you will receive JSON-encoded data containing a tasks array with the information specific to the set tasks.
Description of the fields in the results array:
5integerthe number of 5-star ratings
Field name
Type
Description
version
string
the current version of the API
status_code
integer
general status code
you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions
status_message
string
general informational message
you can find the full list of general informational messages here
time
string
execution time, seconds
cost
float
total tasks cost, USD
tasks_count
integer
the number of tasks in the tasksarray
tasks_error
integer
the number of tasks in the tasks array returned with an error
status code of the task
generated by DataForSEO; can be within the following range: 10000-60000
status_message
string
informational message of the task
time
string
execution time, seconds
cost
float
cost of the task, USD
result_count
integer
number of elements in the result array
path
array
URL path
data
object
contains the same parameters that you specified in the POST request
result
array
array of results
total_count
integer
total number of results in our database relevant to your request
count
integer
item types
the number of items in the items array
offset
integer
offset in the results array of returned businesses
offset_token
string
token for subsequent requests
by specifying the unique offset_token when setting a new task, you will get the subsequent results of the initial task; offset_token values are unique for each subsequent task
items
array
encountered item types
types of search engine results encountered in the items array;
possible item types: business_listing
type
string
type of element = ‘business_listing’
title
string
title of the element in SERP
the name of the business entity for which the results are collected
description
string
description of the element in SERP
the description of the business entity for which the results are collected
category
string
business category
Google My Business general category that best describes the services provided by the business entity
category_ids
array
global category IDs
universal category IDs that do not change based on the selected country
additional_categories
array
additional business categories
additional Google My Business categories that describe the services provided by the business entity in more detail
cid
string
google-defined client id
unique id of a local establishment
learn more about the identifier in this help center article
feature_id
string
the unique identifier of the element in SERP
learn more about the identifier in this help center article
address
string
address of the business entity
address_info
object
object containing address components of the business entity
borough
string
administrative unit or district the business entity location belongs to
address
string
street address of the business entity
city
string
name of the city where the business entity is located
zip
string
ZIP code of the business entity
region
string
DMA region of the business entity location
country_code
string
ISO country code of the business entity location
place_id
string
unique place identifier place id of the local establishment featured in the element
learn more about the identifier in this help center article
phone
string
phone number of the business entity
url
string
absolute url of the business entity
domain
string
domain of the business entity
logo
string
URL of the logo featured in Google My Business profile
main_image
string
URL of the main image featured in Google My Business profile
total_photos
integer
total count of images featured in Google My Business profile
snippet
string
additional information on the business entity
latitude
float
latitude coordinate of the local establishments in google maps
example: "latitude": 51.584091
longitude
float
longitude coordinate of the local establishment in google maps
example: "longitude": -0.31365919999999997
is_claimed
boolean
shows whether the entity is verified by its owner on Google Maps
attributes
object
service details in a form of user-reviewed checks;
service details of a business entity displayed in a form of checks and based on user feedback and business category
available_attributes
object
available attributes
indicates attributes a business entity can offer
unavailable_attributes
object
unavailable attributes
indicates attributes a business entity cannot offer
place_topics
object
keywords mentioned in customer reviews
contains most popular keywords related to products/services mentioned in customer reviews of a business entity and the number of reviews mentioning each keyword
example:
"place_topics": {
"egg roll": 48,
"birthday": 33
}
rating
object
the element’s rating
the popularity rate based on reviews and displayed in SERP
rating_type
string
the type of rating
here you can find the following elements: Max5, Percents, CustomMax
value
integer
the value of the rating
votes_count
integer
the amount of feedback
rating_max
integer
the maximum value for a rating_type
hotel_rating
integer
hotel class rating
class ratings range between 1-5 stars, learn more
if there is no hotel class rating information, the value will be null
price_level
string
property price level
can take values: inexpensive, moderate, expensive, very_expensive
if there is no price level information, the value will be null
rating_distribution
object
the distribution of ratings of the business entity
the object displays the number of 1-star to 5-star ratings, as reviewed by users
1
integer
the number of 1-star ratings
2
integer
the number of 2-star ratings
3
integer
the number of 3-star ratings
4
integer
the number of 4-star ratings
5
integer
the number of 5-star ratings
people_also_search
array
related business entities
cid
string
google-defined client id
unique id of a local establishment
learn more about the identifier in this help center article
feature_id
string
the unique identifier of the element in SERP
learn more about the identifier in this help center article
title
string
title of the element in SERP
the name of the business entity for which the results are collected
rating
object
the element’s rating
the popularity rate based on reviews and displayed in SERP
rating_type
string
the type of rating
here you can find the following elements: Max5, Percents, CustomMax
value
integer
the value of the rating
votes_count
integer
the amount of feedback
rating_max
integer
the maximum value for a rating_type
work_time
object
work time details
information related to operational hours of the business entity
work_hours
object
open hours
information about work hours of the local establishment
timetable
object
work hours timetable
sunday
array
work hours on Sunday can take values of the corresponding days of the week
open
object
opening time
hour
integer
hours in the 24-hour format
minute
integer
minutes
close
object
closing time
hour
integer
hours in the 24-hour format
minute
integer
minutes
current_status
string
current status of the establishment
possible values: open, close, temporarily_closed, closed_forever
popular_times
object
popular times
information related to busy hours of the business entity
popular_times_by_days
object
popular hours
information about busy hours of the local establishment on each day of the week
sunday
array
busy hours on Sunday can take values of the corresponding days of the week
time
object
busy hours
hour
integer
hours in a 24-hour format
minute
integer
minutes
popular_index
integer
popularity index
relative time-bound popularity index measured from 0 to 100;
higher value corresponds to a busier time of a day
local_business_links
array
available interactions with the business
list of options to interact with the business directly from search results
type
string
type of element
possible values: "reservation"
"order"
"delivery_services_element"
"menu"
title
string
title of the element
domain of the reservation software
url
string
URL to the services
contact_info
array
available contacts of the business
list of contacts to interact with the business
type
string
type of contact element
value
string
contact displayed in SERP
example: "+119797979736"
source
string
data source
check_url
string
direct URL to search engine results
you can use it to make sure that we provided accurate results
last_updated_time
string
date and time when the data was last updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2023-01-26 09:03:15 +00:00
first_seen
string
date and time when our crawler found the business listing element for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2023-03-11 10:04:11 +00:00